Next: Completion Variables, Previous: High-Level Completion, Up: Completion [Contents][Index]
The high-level completion functions
read-file-name, read-directory-name,
and read-shell-command are designed to read file
names, directory names, and shell commands, respectively. They
provide special features, including automatic insertion of the
default directory.
This function reads a file name, prompting with prompt and providing completion.
As an exception, this function reads a file name using a graphical file dialog instead of the minibuffer, if all of the following are true:
use-dialog-box is
non-nil. See
Dialog Boxes in The GNU Emacs Manual.The exact behavior when using a graphical file dialog is platform-dependent. Here, we simply document the behavior when using the minibuffer.
read-file-name does not automatically expand
the returned file name. You must call
expand-file-name yourself if an absolute file
name is required.
The optional argument require-match has the
same meaning as in completing-read. See Minibuffer
Completion.
The argument directory specifies the directory
to use for completing relative file names. It should be an
absolute directory name. If the variable
insert-default-directory is
non-nil, directory is also inserted
in the minibuffer as initial input. It defaults to the
current buffer’s value of
default-directory.
If you specify initial, that is an initial file
name to insert in the buffer (after directory, if
that is inserted). In this case, point goes at the beginning
of initial. The default for initial is
nil—don’t insert any file name. To
see what initial does, try the command C-x
C-v in a buffer visiting a file. Please
note: we recommend using default rather
than initial in most cases.
If default is non-nil, then the
function returns default if the user exits the
minibuffer with the same non-empty contents that
read-file-name inserted initially. The initial
minibuffer contents are always non-empty if
insert-default-directory is
non-nil, as it is by default. default
is not checked for validity, regardless of the value of
require-match. However, if
require-match is non-nil, the initial
minibuffer contents should be a valid file (or directory)
name. Otherwise read-file-name attempts
completion if the user exits without any editing, and does
not return default. default is also
available through the history commands.
If default is nil,
read-file-name tries to find a substitute
default to use in its place, which it treats in exactly the
same way as if it had been specified explicitly. If
default is nil, but
initial is non-nil, then the default
is the absolute file name obtained from directory
and initial. If both default and
initial are nil and the buffer is
visiting a file, read-file-name uses the
absolute file name of that file as default. If the buffer is
not visiting a file, then there is no default. In that case,
if the user types RET without any
editing, read-file-name simply returns the
pre-inserted contents of the minibuffer.
If the user types RET in an empty minibuffer, this function returns an empty string, regardless of the value of require-match. This is, for instance, how the user can make the current buffer visit no file using M-x set-visited-file-name.
If predicate is non-nil, it
specifies a function of one argument that decides which file
names are acceptable completion alternatives. A file name is
an acceptable value if predicate returns
non-nil for it.
Here is an example of using
read-file-name:
(read-file-name "The file is ") ;; After evaluation of the preceding expression, ;; the following appears in the minibuffer:
---------- Buffer: Minibuffer ---------- The file is /gp/gnu/elisp/∗ ---------- Buffer: Minibuffer ----------
Typing manual TAB results in the following:
---------- Buffer: Minibuffer ---------- The file is /gp/gnu/elisp/manual.texi∗ ---------- Buffer: Minibuffer ----------
If the user types RET,
read-file-name returns the file name as the
string "/gp/gnu/elisp/manual.texi".
If non-nil, this should be a function that
accepts the same arguments as read-file-name.
When read-file-name is called, it calls this
function with the supplied arguments instead of doing its
usual work.
If this variable is non-nil,
read-file-name ignores case when performing
completion.
This function is like read-file-name but
allows only directory names as completion alternatives.
If default is nil and
initial is non-nil,
read-directory-name constructs a substitute
default by combining directory (or the current
buffer’s default directory if directory is
nil) and initial. If both
default and initial are
nil, this function uses directory as
substitute default, or the current buffer’s default
directory if directory is nil.
This variable is used by read-file-name, and
thus, indirectly, by most commands reading file names. (This
includes all commands that use the code letters
‘f’ or ‘F’
in their interactive form. See Code Characters
for interactive.) Its value controls whether
read-file-name starts by placing the name of the
default directory in the minibuffer, plus the initial file
name, if any. If the value of this variable is
nil, then read-file-name does not
place any initial input in the minibuffer (unless you specify
initial input with the initial argument). In that
case, the default directory is still used for completion of
relative file names, but is not displayed.
If this variable is nil and the initial
minibuffer contents are empty, the user may have to
explicitly fetch the next history element to access a default
value. If the variable is non-nil, the initial
minibuffer contents are always non-empty and the user can
always request a default value by immediately typing
RET in an unedited minibuffer. (See
above.)
For example:
;; Here the minibuffer starts out with the default directory.
(let ((insert-default-directory t))
(read-file-name "The file is "))
---------- Buffer: Minibuffer ---------- The file is ~lewis/manual/∗ ---------- Buffer: Minibuffer ----------
;; Here the minibuffer is empty and only the prompt ;; appears on its line. (let ((insert-default-directory nil)) (read-file-name "The file is "))
---------- Buffer: Minibuffer ---------- The file is ∗ ---------- Buffer: Minibuffer ----------
This function reads a shell command from the minibuffer, prompting with prompt and providing intelligent completion. It completes the first word of the command using candidates that are appropriate for command names, and the rest of the command words as file names.
This function uses
minibuffer-local-shell-command-map as the keymap
for minibuffer input. The history argument
specifies the history list to use; if is omitted or
nil, it defaults to
shell-command-history (see shell-command-history).
The optional argument initial specifies the
initial content of the minibuffer (see Initial Input). The
rest of args, if present, are used as the
default and inherit-input-method
arguments in read-from-minibuffer (see Text from
Minibuffer).
This keymap is used by read-shell-command for
completing command and file names that are part of a shell
command. It uses minibuffer-local-map as its
parent keymap, and binds TAB to
completion-at-point.
Next: Completion Variables, Previous: High-Level Completion, Up: Completion [Contents][Index]